   This is an introduction to `Programming in Emacs Lisp', for people
who are not programmers.

   Edition 2.04, 2001 Dec 17

   Copyright (C) 1990, '91, '92, '93, '94, '95, '97, 2001 Free Software
Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Section being the Preface, with the Front-Cover Texts being
no Front-Cover Texts, and with the Back-Cover Texts being no Back-Cover
Texts.  A copy of the license is included in the section entitled "GNU
Free Documentation License".

A Modified Mode Line
====================

   Finally, a feature I really like: a modified mode line.

   When I work over a network, I forget which machine I am using.  Also,
I tend to I lose track of where I am, and which line point is on.

   So I reset my mode line to look like this:

     -:-- foo.texi   rattlesnake:/home/bob/  Line 1  (Texinfo Fill) Top

   I am visiting a file called `foo.texi', on my machine `rattlesnake'
in my `/home/bob' buffer.  I am on line 1, in Texinfo mode, and am at
the top of the buffer.

   My `.emacs' file has a section that looks like this:

     ;; Set a Mode Line that tells me which machine, which directory,
     ;; and which line I am on, plus the other customary information.
     (setq default-mode-line-format
      (quote
       (#("-" 0 1
          (help-echo
           "mouse-1: select window, mouse-2: delete others ..."))
        mode-line-mule-info
        mode-line-modified
        mode-line-frame-identification
        "    "
        mode-line-buffer-identification
        "    "
        (:eval (substring
                (system-name) 0 (string-match "\\..+" (system-name))))
        ":"
        default-directory
        #(" " 0 1
          (help-echo
           "mouse-1: select window, mouse-2: delete others ..."))
        (line-number-mode " Line %l ")
        global-mode-string
        #("   %[(" 0 6
          (help-echo
           "mouse-1: select window, mouse-2: delete others ..."))
        (:eval (mode-line-mode-name))
        mode-line-process
        minor-mode-alist
        #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...)))
        ")%] "
        (-3 . "%P")
        ;;   "-%-"
        )))

Here, I redefine the default mode line.  Most of the parts are from the
original; but I make a few changes.  I set the _default_ mode line
format so as to permit various modes, such as Info, to override it.

   Many elements in the list are self-explanatory: `mode-line-modified'
is a variable that tells whether the buffer has been modified,
`mode-name' tells the name of the mode, and so on.  However, the format
looks complicated because of two features we have not discussed.

   The first string in the mode line is a dash or hyphen, `-'.  In the
old days, it would have been specified simply as `"-"'.  But nowadays,
Emacs can add properties to a string, such as highlighting or, as in
this case, a help feature.  If you place your mouse cursor over the
hyphen, some help information appears  (By default, you must wait one
second before the information appears.  You can change that timing by
changing the value of `tooltip-delay'.)

   The new string format has a special syntax:

     #("-" 0 1 (help-echo "mouse-1: select window, ..."))

The `#(' begins a list.  The first element of the list is the string
itself, just one `-'.  The second and third elements specify the range
over which the fourth element applies.  A range starts _after_ a
character, so a zero means the range starts just before the first
character; a 1 means that the range ends just after the first
character.  The third element is the property for the range.  It
consists of a property list,  a property name, in this case,
`help-echo', followed by a value, in this case, a string.  The second,
third, and fourth elements of this new string format can be repeated.

   See Text Properties in String (elisp), and
see Mode Line Format (elisp), for more
information.

   `mode-line-buffer-identification' displays the current buffer name.
It is a list beginning `(#("%12b" 0 4 ...'.  The `#(' begins the list.

   The `"%12b"' displays the current buffer name, using the
`buffer-name' function with which we are familiar; the `12' specifies
the maximum number of characters that will be displayed.  When a name
has fewer characters, whitespace is added to fill out to this number.
(Buffer names can and often should be longer than 12 characters; this
length works well in a typical 80 column wide window.)

   `:eval' is a new feature in GNU Emacs version 21.  It says to
evaluate the following form and use the result as a string to display.
In this case, the expression displays the first component of the full
system name.  The end of the first component is a `.' (`period'), so I
use the `string-match' function to tell me the length of the first
component.  The substring from the zeroth character to that length is
the name of the machine.

   This is the expression:

     (:eval (substring
             (system-name) 0 (string-match "\\..+" (system-name))))

   `%[' and `%]' cause a pair of square brackets to appear for each
recursive editing level.  `%n' says `Narrow' when narrowing is in
effect.  `%P' tells you the percentage of the buffer that is above the
bottom of the window, or `Top', `Bottom', or `All'.  (A lower case `p'
tell you the percentage above the _top_ of the window.)  `%-' inserts
enough dashes to fill out the line.

   Remember, "You don't have to like Emacs to like it" -- your own
Emacs can have different colors, different commands, and different keys
than a default Emacs.

   On the other hand, if you want to bring up a plain `out of the box'
Emacs, with no customization, type:

     emacs -q

This will start an Emacs that does _not_ load your `~/.emacs'
initialization file.  A plain, default Emacs.  Nothing more.

Debugging
*********

   GNU Emacs has two debuggers, `debug' and `edebug'.  The first is
built into the internals of Emacs and is always with you; the second
requires that you instrument a function before you can use it.

   Both debuggers are described extensively in Debugging Lisp Programs (elisp).
In this chapter, I will walk through a
short example of each.

`debug'
=======

   Suppose you have written a function definition that is intended to
return the sum of the numbers 1 through a given number.  (This is the
`triangle' function discussed earlier.  See Example with Decrementing Counter,
for a discussion.)

   However, your function definition has a bug.  You have mistyped `1='
for `1-'.  Here is the broken definition:

     (defun triangle-bugged (number)
       "Return sum of numbers 1 through NUMBER inclusive."
       (let ((total 0))
         (while (> number 0)
           (setq total (+ total number))
           (setq number (1= number)))      ; Error here.
         total))

   If you are reading this in Info, you can evaluate this definition in
the normal fashion.  You will see `triangle-bugged' appear in the echo
area.

   Now evaluate the `triangle-bugged' function with an argument of 4:

     (triangle-bugged 4)

In GNU Emacs version 21, you will create and enter a `*Backtrace*'
buffer that says:

     ---------- Buffer: *Backtrace* ----------
     Debugger entered--Lisp error: (void-function 1=)
       (1= number)
       (setq number (1= number))
       (while (> number 0) (setq total (+ total number))
             (setq number (1= number)))
       (let ((total 0)) (while (> number 0) (setq total ...)
         (setq number ...)) total)
       triangle-bugged(4)
       eval((triangle-bugged 4))
       eval-last-sexp-1(nil)
       eval-last-sexp(nil)
       call-interactively(eval-last-sexp)
     ---------- Buffer: *Backtrace* ----------

(I have reformatted this example slightly; the debugger does not fold
long lines.  As usual, you can quit the debugger by typing `q' in the
`*Backtrace*' buffer.)

   In practice, for a bug as simple as this, the `Lisp error' line will
tell you what you need to know to correct the definition.  The function
`1=' is `void'.

   In GNU Emacs 20 and before, you will see:

     Symbol's function definition is void: 1=

which has the same meaning as the `*Backtrace*' buffer line in version
21.

   However, suppose you are not quite certain what is going on?  You
can read the complete backtrace.

   In this case, you need to run GNU Emacs 21, which automatically
starts the debugger that puts you in the `*Backtrace*' buffer; or else,
you need to start the debugger manually as described below.

   Read the `*Backtrace*' buffer from the bottom up; it tells you what
Emacs did that led to the error.  Emacs made an interactive call to
`C-x C-e' (`eval-last-sexp'), which led to the evaluation of the
`triangle-bugged' expression.  Each line above tells you what the Lisp
interpreter evaluated next.

   The third line from the top of the buffer is

     (setq number (1= number))

Emacs tried to evaluate this expression; in order to do so, it tried to
evaluate the inner expression shown on the second line from the top:

     (1= number)

This is where the error occurred; as the top line says:

     Debugger entered--Lisp error: (void-function 1=)

You can correct the mistake, re-evaluate the function definition, and
then run your test again.

`debug-on-entry'
================

   GNU Emacs 21 starts the debugger automatically when your function has
an error.  GNU Emacs version 20 and before did not; it simply presented
you with an error message.  You had to start the debugger manually.

   You can start the debugger manually for all versions of Emacs; the
advantage is that the debugger runs even if you do not have a bug in
your code.  Sometimes your code will be free of bugs!

   You can enter the debugger when you call the function by calling
`debug-on-entry'.

Type:

     M-x debug-on-entry RET triangle-bugged RET

Now, evaluate the following:

     (triangle-bugged 5)

All versions of Emacs will create a `*Backtrace*' buffer and tell you
that it is beginning to evaluate the `triangle-bugged' function:

     ---------- Buffer: *Backtrace* ----------
     Debugger entered--entering a function:
     * triangle-bugged(5)
       eval((triangle-bugged 5))
       eval-last-sexp-1(nil)
       eval-last-sexp(nil)
       call-interactively(eval-last-sexp)
     ---------- Buffer: *Backtrace* ----------

   In the `*Backtrace*' buffer, type `d'.  Emacs will evaluate the
first expression in `triangle-bugged'; the buffer will look like this:

     ---------- Buffer: *Backtrace* ----------
     Debugger entered--beginning evaluation of function call form:
     * (let ((total 0)) (while (> number 0) (setq total ...)
             (setq number ...)) total)
     * triangle-bugged(5)
       eval((triangle-bugged 5))
       eval-last-sexp-1(nil)
       eval-last-sexp(nil)
       call-interactively(eval-last-sexp)
     ---------- Buffer: *Backtrace* ----------

Now, type `d' again, eight times, slowly.  Each time you type `d',
Emacs will evaluate another expression in the function definition.

   Eventually, the buffer will look like this:

     ---------- Buffer: *Backtrace* ----------
     Debugger entered--beginning evaluation of function call form:
     * (setq number (1= number))
     * (while (> number 0) (setq total (+ total number))
             (setq number (1= number)))
     * (let ((total 0)) (while (> number 0) (setq total ...)
             (setq number ...)) total)
     * triangle-bugged(5)
       eval((triangle-bugged 5))
       eval-last-sexp-1(nil)
       eval-last-sexp(nil)
       call-interactively(eval-last-sexp)
     ---------- Buffer: *Backtrace* ----------

Finally, after you type `d' two more times, Emacs will reach the error,
and the top two lines of the `*Backtrace*' buffer will look like this:

     ---------- Buffer: *Backtrace* ----------
     Debugger entered--Lisp error: (void-function 1=)
     * (1= number)
     ...
     ---------- Buffer: *Backtrace* ----------

   By typing `d', you were able to step through the function.

   You can quit a `*Backtrace*' buffer by typing `q' in it; this quits
the trace, but does not cancel `debug-on-entry'.

   To cancel the effect of `debug-on-entry', call
`cancel-debug-on-entry' and the name of the function, like this:

     M-x cancel-debug-on-entry RET triangle-bugged RET

(If you are reading this in Info, cancel `debug-on-entry' now.)

`debug-on-quit' and `(debug)'
=============================

   In addition to setting `debug-on-error' or calling `debug-on-entry',
there are two other ways to start `debug'.

   You can start `debug' whenever you type `C-g' (`keyboard-quit') by
setting the variable `debug-on-quit' to `t'.  This is useful for
debugging infinite loops.

   Or, you can insert a line that says `(debug)' into your code where
you want the debugger to start, like this:

     (defun triangle-bugged (number)
       "Return sum of numbers 1 through NUMBER inclusive."
       (let ((total 0))
         (while (> number 0)
           (setq total (+ total number))
           (debug)                         ; Start debugger.
           (setq number (1= number)))      ; Error here.
         total))

   The `debug' function is described in detail in The Lisp Debugger (elisp).

The `edebug' Source Level Debugger
==================================

   Edebug is a source level debugger.  Edebug normally displays the
source of the code you are debugging, with an arrow at the left that
shows which line you are currently executing.

   You can walk through the execution of a function, line by line, or
run quickly until reaching a "breakpoint" where execution stops.

   Edebug is described in Edebug (elisp).

   Here is a bugged function definition for `triangle-recursively'.
See Recursion in place of a counter, for
a review of it.

     (defun triangle-recursively-bugged (number)
       "Return sum of numbers 1 through NUMBER inclusive.
     Uses recursion."
       (if (= number 1)
           1
         (+ number
            (triangle-recursively-bugged
             (1= number)))))               ; Error here.

Normally, you would install this definition by positioning your cursor
after the function's closing parenthesis and typing `C-x C-e'
(`eval-last-sexp') or else by positioning your cursor within the
definition and typing `C-M-x' (`eval-defun').  (By default, the
`eval-defun' command works only in Emacs Lisp mode or in Lisp
Interactive mode.)

   However, to prepare this function definition for Edebug, you must
first "instrument" the code using a different command.  You can do this
by positioning your cursor within the definition and typing

     M-x edebug-defun RET

This will cause Emacs to load Edebug automatically if it is not already
loaded, and properly instrument the function.

   After instrumenting the function, place your cursor after the
following expression and type `C-x C-e' (`eval-last-sexp'):

     (triangle-recursively-bugged 3)

You will be jumped back to the source for `triangle-recursively-bugged'
and the cursor positioned at the beginning of the `if' line of the
function.  Also, you will see an arrowhead at the left hand side of
that line.  The arrowhead marks the line where the function is
executing.  (In the following examples, we show the arrowhead with
`=>'; in a windowing system, you may see the arrowhead as a solid
triangle in the window `fringe'.)

     =>-!-(if (= number 1)

In the example, the location of point is displayed as `-!-' (in a
printed book, it is displayed with a five pointed star).

If you now press <SPC>, point will move to the next expression to be
executed; the line will look like this:

     =>(if -!-(= number 1)

As you continue to press <SPC>, point will move from expression to
expression.  At the same time, whenever an expression returns a value,
that value will be displayed in the echo area.  For example, after you
move point past `number', you will see the following:

     Result: 3 = C-c

This means the value of `number' is 3, which is ASCII `control-c' (the
third letter of the alphabet).

   You can continue moving through the code until you reach the line
with the error.  Before evaluation, that line looks like this:

     =>        -!-(1= number)))))               ; Error here.

When you press <SPC> once again, you will produce an error message that
says:

     Symbol's function definition is void: 1=

This is the bug.

   Press `q' to quit Edebug.

   To remove instrumentation from a function definition, simply
re-evaluate it with a command that does not instrument it.  For
example, you could place your cursor after the definition's closing
parenthesis and type `C-x C-e'.

   Edebug does a great deal more than walk with you through a function.
You can set it so it races through on its own, stopping only at an
error or at specified stopping points; you can cause it to display the
changing values of various expressions; you can find out how many times
a function is called, and more.

   Edebug is described in Edebug (elisp).

Debugging Exercises
===================

   * Install the `count-words-region' function and then cause it to
     enter the built-in debugger when you call it.  Run the command on a
     region containing two words.  You will need to press `d' a
     remarkable number of times.  On your system, is a `hook' called
     after the command finishes?  (For information on hooks, see
     Command Loop Overview (elisp).)

   * Copy `count-words-region' into the `*scratch*' buffer, instrument
     the function for Edebug, and walk through its execution.  The
     function does not need to have a bug, although you can introduce
     one if you wish.  If the function lacks a bug, the walk-through
     completes without problems.

   * While running Edebug, type `?' to see a list of all the Edebug
     commands.  (The `global-edebug-prefix' is usually `C-x X', i.e.
     `<CTL>-x' followed by an upper case `X'; use this prefix for
     commands made outside of the Edebug debugging buffer.)

   * In the Edebug debugging buffer, use the `p'
     (`edebug-bounce-point') command to see where in the region the
     `count-words-region' is working.

   * Move point to some spot further down function and then type the
     `h' (`edebug-goto-here') command to jump to that location.

   * Use the `t' (`edebug-trace-mode') command to cause Edebug to walk
     through the function on its own; use an upper case `T' for
     `edebug-Trace-fast-mode'.

   * Set a breakpoint, then run Edebug in Trace mode until it reaches
     the stopping point.

Conclusion
**********

   We have now reached the end of this Introduction.  You have now
learned enough about programming in Emacs Lisp to set values, to write
simple `.emacs' files for yourself and your friends, and write simple
customizations and extensions to Emacs.

   This is a place to stop.  Or, if you wish, you can now go onward, and
teach yourself.

   You have learned some of the basic nuts and bolts of programming.
But only some.  There are a great many more brackets and hinges that are
easy to use that we have not touched.

   A path you can follow right now lies among the sources to GNU Emacs
and in The GNU Emacs Lisp Reference Manual (elisp).

   The Emacs Lisp sources are an adventure.  When you read the sources
and come across a function or expression that is unfamiliar, you need to
figure out or find out what it does.

   Go to the Reference Manual.  It is a thorough, complete, and fairly
easy-to-read description of Emacs Lisp.  It is written not only for
experts, but for people who know what you know.  (The `Reference
Manual' comes with the standard GNU Emacs distribution.  Like this
introduction, it comes as a Texinfo source file, so you can read it
on-line and as a typeset, printed book.)

   Go to the other on-line help that is part of GNU Emacs: the on-line
documentation for all functions, and `find-tags', the program that
takes you to sources.

   Here is an example of how I explore the sources.  Because of its
name, `simple.el' is the file I looked at first, a long time ago.  As
it happens some of the functions in `simple.el' are complicated, or at
least look complicated at first sight.  The `open-line' function, for
example, looks complicated.

   You may want to walk through this function slowly, as we did with the
`forward-sentence' function.  (see forward-sentence.)  Or you may
want to skip that function and look at another, such as `split-line'.
You don't need to read all the functions.  According to
`count-words-in-defun', the `split-line' function contains 27 words and
symbols.

   Even though it is short, `split-line' contains four expressions we
have not studied: `skip-chars-forward', `indent-to', `current-column'
and `?\n'.

   Consider the `skip-chars-forward' function.  (It is part of the
function definition for `back-to-indentation', which is shown in
Review.)

   In GNU Emacs, you can find out more about `skip-chars-forward' by
typing `C-h f' (`describe-function') and the name of the function.
This gives you the function documentation.

   You may be able to guess what is done by a well named function such
as `indent-to'; or you can look it up, too.  Incidentally, the
`describe-function' function itself is in `help.el'; it is one of those
long, but decipherable functions.  You can look up `describe-function'
using the `C-h f' command!

   In this instance, since the code is Lisp, the `*Help*' buffer
contains the name of the library containing the function's source.  You
can put point over the name of the library and press the RET key, which
in this situation is bound to `help-follow', and be taken directly to
the source, in the same way as `M-.' (`find-tag').

   The definition for `describe-function' illustrates how to customize
the `interactive' expression without using the standard character
codes; and it shows how to create a temporary buffer.

   (The `indent-to' function is written in C rather than Emacs Lisp; it
is a `built-in' function.  `help-follow' only provides you with the
documentation of a built-in function; it does not take you to the
source.  But `find-tag' will take you to the source, if properly set
up.)

   You can look at a function's source using `find-tag', which is bound
to `M-.'  Finally, you can find out what the Reference Manual has to
say by visiting the manual in Info, and typing `i' (`Info-index') and
the name of the function, or by looking up `skip-chars-forward' in the
index to a printed copy of the manual.

   Similarly, you can find out what is meant by `?\n'.  You can try
using `Info-index' with `?\n'.  It turns out that this action won't
help; but don't give up.  If you search the index for `\n' without the
`?', you will be taken directly to the relevant section of the manual.
(see Character Type (elisp).  `?\n' stands for the
newline character.)

   Other interesting source files include `paragraphs.el',
`loaddefs.el', and `loadup.el'.  The `paragraphs.el' file includes
short, easily understood functions as well as longer ones.  The
`loaddefs.el' file contains the many standard autoloads and many
keymaps.  I have never looked at it all; only at parts.  `loadup.el' is
the file that loads the standard parts of Emacs; it tells you a great
deal about how Emacs is built.  (see Building Emacs (elisp),
for more about building.)

   As I said, you have learned some nuts and bolts; however, and very
importantly, we have hardly touched major aspects of programming; I
have said nothing about how to sort information, except to use the
predefined `sort' function; I have said nothing about how to store
information, except to use variables and lists; I have said nothing
about how to write programs that write programs.  These are topics for
another, and different kind of book, a different kind of learning.

   What you have done is learn enough for much practical work with GNU
Emacs.  What you have done is get started.  This is the end of a
beginning.

The `the-the' Function
**********************

   Sometimes when you you write text, you duplicate words--as with "you
you" near the beginning of this sentence.  I find that most frequently,
I duplicate "the'; hence, I call the function for detecting duplicated
words, `the-the'.

   As a first step, you could use the following regular expression to
search for duplicates:

     \\(\\w+[ \t\n]+\\)\\1

This regexp matches one or more word-constituent characters followed by
one or more spaces, tabs, or newlines.  However, it does not detect
duplicated words on different lines, since the ending of the first
word, the end of the line, is different from the ending of the second
word, a space.  (For more information about regular expressions, see
Regular Expression Searches, as well as
Syntax of Regular Expressions (emacs), and Regular Expressions (elisp).)

   You might try searching just for duplicated word-constituent
characters but that does not work since the pattern detects doubles
such as the two occurrences of `th' in `with the'.

   Another possible regexp searches for word-constituent characters
followed by non-word-constituent characters, reduplicated.  Here,
`\\w+' matches one or more word-constituent characters and `\\W*'
matches zero or more non-word-constituent characters.

     \\(\\(\\w+\\)\\W*\\)\\1

Again, not useful.

   Here is the pattern that I use.  It is not perfect, but good enough.
`\\b' matches the empty string, provided it is at the beginning or end
of a word; `[^@ \n\t]+' matches one or more occurrences of any
characters that are _not_ an @-sign, space, newline, or tab.

     \\b\\([^@ \n\t]+\\)[ \n\t]+\\1\\b

   One can write more complicated expressions, but I found that this
expression is good enough, so I use it.

   Here is the `the-the' function, as I include it in my `.emacs' file,
along with a handy global key binding:

     (defun the-the ()
       "Search forward for for a duplicated word."
       (interactive)
       (message "Searching for for duplicated words ...")
       (push-mark)
       ;; This regexp is not perfect
       ;; but is fairly good over all:
       (if (re-search-forward
            "\\b\\([^@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move)
           (message "Found duplicated word.")
         (message "End of buffer")))

     ;; Bind `the-the' to  C-c \
     (global-set-key "\C-c\\" 'the-the)

   Here is test text:

     one two two three four five
     five six seven

   You can substitute the other regular expressions shown above in the
function definition and try each of them on this list.

Handling the Kill Ring
**********************

   The kill ring is a list that is transformed into a ring by the
workings of the `rotate-yank-pointer' function.  The `yank' and
`yank-pop' commands use the `rotate-yank-pointer' function.  This
appendix describes the `rotate-yank-pointer' function as well as both
the `yank' and the `yank-pop' commands.

The `rotate-yank-pointer' Function
==================================

   The `rotate-yank-pointer' function changes the element in the kill
ring to which `kill-ring-yank-pointer' points.  For example, it can
change  `kill-ring-yank-pointer' from pointing to the second element to
point to the third element.

   Here is the code for `rotate-yank-pointer':

     (defun rotate-yank-pointer (arg)
       "Rotate the yanking point in the kill ring."
       (interactive "p")
       (let ((length (length kill-ring)))
         (if (zerop length)
             ;; then-part
             (error "Kill ring is empty")
           ;; else-part
           (setq kill-ring-yank-pointer
                 (nthcdr (% (+ arg
                               (- length
                                  (length
                                   kill-ring-yank-pointer)))
                            length)
                         kill-ring)))))

`rotate-yank-pointer' in Outline
--------------------------------

   The `rotate-yank-pointer' function looks complex, but as usual, it
can be understood by taking it apart piece by piece.  First look at it
in skeletal form:

     (defun rotate-yank-pointer (arg)
       "Rotate the yanking point in the kill ring."
       (interactive "p")
       (let VARLIST
         BODY...)

   This function takes one argument, called `arg'.  It has a brief
documentation string; and it is interactive with a small `p', which
means that the argument must be a processed prefix passed to the
function as a number.

   The body of the function definition is a `let' expression, which
itself has a body as well as a VARLIST.

   The `let' expression declares a variable that will be only usable
within the bounds of this function.  This variable is called `length'
and is bound to a value that is equal to the number of items in the
kill ring.  This is done by using the function called `length'.  (Note
that this function has the same name as the variable called `length';
but one use of the word is to name the function and the other is to
name the variable.  The two are quite distinct.  Similarly, an English
speaker will distinguish between the meanings of the word `ship' when
he says: "I must ship this package immediately." and "I must get aboard
the ship immediately.")

   The function `length' tells the number of items there are in a list,
so `(length kill-ring)' returns the number of items there are in the
kill ring.

The Body of `rotate-yank-pointer'
---------------------------------

   The body of `rotate-yank-pointer' is a `let' expression and the body
of the `let' expression is an `if' expression.

   The purpose of the `if' expression is to find out whether there is
anything in the kill ring.  If the kill ring is empty, the `error'
function stops evaluation of the function and prints a message in the
echo area.  On the other hand, if the kill ring has something in it, the
work of the function is done.

   Here is the if-part and then-part of the `if' expression:

     (if (zerop length)                      ; if-part
         (error "Kill ring is empty")        ; then-part
       ...

If there is not anything in the kill ring, its length must be zero and
an error message sent to the user: `Kill ring is empty'.  The `if'
expression uses the function `zerop' which returns true if the value it
is testing is zero.  When `zerop' tests true, the then-part of the `if'
is evaluated.  The then-part is a list starting with the function
`error', which is a function that is similar to the `message' function
(see message), in that it prints a one-line message in the echo
area.  However, in addition to printing a message, `error' also stops
evaluation of the function within which it is embedded.  This means
that the rest of the function will not be evaluated if the length of
the kill ring is zero.

Digression about the word `error'
.................................

   (In my opinion, it is slightly misleading, at least to humans, to use
the term `error' as the name of the `error' function.  A better term
would be `cancel'.  Strictly speaking, of course, you cannot point to,
much less rotate a pointer to a list that has no length, so from the
point of view of the computer, the word `error' is correct.  But a
human expects to attempt this sort of thing, if only to find out
whether the kill ring is full or empty.  This is an act of exploration.

   (From the human point of view, the act of exploration and discovery
is not necessarily an error, and therefore should not be labelled as
one, even in the bowels of a computer.  As it is, the code in Emacs
implies that a human who is acting virtuously, by exploring his or her
environment, is making an error.  This is bad.  Even though the computer
takes the same steps as it does when there is an `error', a term such as
`cancel' would have a clearer connotation.)

The else-part of the `if' expression
....................................

   The else-part of the `if' expression is dedicated to setting the
value of `kill-ring-yank-pointer' when the kill ring has something in
it.  The code looks like this:

     (setq kill-ring-yank-pointer
           (nthcdr (% (+ arg
                         (- length
                            (length kill-ring-yank-pointer)))
                      length)
                   kill-ring)))))

   This needs some examination.  Clearly, `kill-ring-yank-pointer' is
being set to be equal to some CDR of the kill ring, using the `nthcdr'
function that is described in an earlier section.  (see
copy-region-as-kill.)  But exactly how does it do this?

   Before looking at the details of the code let's first consider the
purpose of the `rotate-yank-pointer' function.

   The `rotate-yank-pointer' function changes what
`kill-ring-yank-pointer' points to.  If `kill-ring-yank-pointer' starts
by pointing to the first element of a list, a call to
`rotate-yank-pointer' causes it to point to the second element; and if
`kill-ring-yank-pointer' points to the second element, a call to
`rotate-yank-pointer' causes it to point to the third element.  (And if
`rotate-yank-pointer' is given an argument greater than 1, it jumps the
pointer that many elements.)

   The `rotate-yank-pointer' function uses `setq' to reset what the
`kill-ring-yank-pointer' points to.  If `kill-ring-yank-pointer' points
to the first element of the kill ring, then, in the simplest case, the
`rotate-yank-pointer' function must cause it to point to the second
element.  Put another way, `kill-ring-yank-pointer' must be reset to
have a value equal to the CDR of the kill ring.

   That is, under these circumstances,

     (setq kill-ring-yank-pointer
        ("some text" "a different piece of text" "yet more text"))

     (setq kill-ring
        ("some text" "a different piece of text" "yet more text"))

the code should do this:

     (setq kill-ring-yank-pointer (cdr kill-ring))

As a result, the `kill-ring-yank-pointer' will look like this:

     kill-ring-yank-pointer
          => ("a different piece of text" "yet more text"))

   The actual `setq' expression uses the `nthcdr' function to do the
job.

   As we have seen before (see nthcdr), the `nthcdr' function works
by repeatedly taking the CDR of a list--it takes the CDR of the CDR of
the CDR ...

   The two following expressions produce the same result:

     (setq kill-ring-yank-pointer (cdr kill-ring))

     (setq kill-ring-yank-pointer (nthcdr 1 kill-ring))

   In the `rotate-yank-pointer' function, however, the first argument
to `nthcdr' is a rather complex looking expression with lots of
arithmetic inside of it:

     (% (+ arg
           (- length
              (length kill-ring-yank-pointer)))
        length)

   As usual, we need to look at the most deeply embedded expression
first and then work our way towards the light.

   The most deeply embedded expression is `(length
kill-ring-yank-pointer)'.  This finds the length of the current value of
the `kill-ring-yank-pointer'.  (Remember that the
`kill-ring-yank-pointer' is the name of a variable whose value is a
list.)

   The measurement of the length is inside the expression:

     (- length (length kill-ring-yank-pointer))

In this expression, the first `length' is the variable that was
assigned the length of the kill ring in the `let' statement at the
beginning of the function.  (One might think this function would be
clearer if the variable `length' were named `length-of-kill-ring'
instead; but if you look at the text of the whole function, you will
see that it is so short that naming this variable `length' is not a
bother, unless you are pulling the function apart into very tiny pieces
as we are doing here.)

   So the line `(- length (length kill-ring-yank-pointer))' tells the
difference between the length of the kill ring and the length of the
list whose name is `kill-ring-yank-pointer'.

   To see how all this fits into the `rotate-yank-pointer' function,
let's begin by analyzing the case where `kill-ring-yank-pointer' points
to the first element of the kill ring, just as `kill-ring' does, and
see what happens when `rotate-yank-pointer' is called with an argument
of 1.

   The variable `length' and the value of the expression `(length
kill-ring-yank-pointer)' will be the same since the variable `length'
is the length of the kill ring and the `kill-ring-yank-pointer' is
pointing to the whole kill ring.  Consequently, the value of

     (- length (length kill-ring-yank-pointer))

will be zero.  Since the value of `arg' will be 1, this will mean that
the value of the whole expression

     (+ arg (- length (length kill-ring-yank-pointer)))

will be 1.

   Consequently, the argument to `nthcdr' will be found as the result of
the expression

     (% 1 length)

The `%' remainder function
..........................

   To understand `(% 1 length)', we need to understand `%'.  According
to its documentation (which I just found by typing `C-h f % <RET>'),
the `%' function returns the remainder of its first argument divided by
its second argument.  For example, the remainder of 5 divided by 2 is
1.  (2 goes into 5 twice with a remainder of 1.)

   What surprises people who don't often do arithmetic is that a smaller
number can be divided by a larger number and have a remainder.  In the
example we just used, 5 was divided by 2.  We can reverse that and ask,
what is the result of dividing 2 by 5?  If you can use fractions, the
answer is obviously 2/5 or .4; but if, as here, you can only use whole
numbers, the result has to be something different.  Clearly, 5 can go
into 2 zero times, but what of the remainder?  To see what the answer
is, consider a case that has to be familiar from childhood:

   * 5 divided by 5 is 1 with a remainder of 0;

   * 6 divided by 5 is 1 with a remainder of 1;

   * 7 divided by 5 is 1 with a remainder of 2.

   * Similarly, 10 divided by 5 is 2 with a remainder of 0;

   * 11 divided by 5 is 2 with a remainder of 1;

   * 12 divided by 5 is 1 with a remainder of 2.

By considering the cases as parallel, we can see that

   * zero divided by 5 must be zero with a remainder of zero;

   * 1 divided by 5 must be zero with a remainder of 1;

   * 2 divided by 5 must be zero with a remainder of 2;

and so on.

   So, in this code, if the value of `length' is 5, then the result of
evaluating

     (% 1 5)

is 1.  (I just checked this by placing the cursor after the expression
and typing `C-x C-e'.  Indeed, 1 is printed in the echo area.)

Using `%' in `rotate-yank-pointer'
..................................

   When the `kill-ring-yank-pointer' points to the beginning of the
kill ring, and the argument passed to `rotate-yank-pointer' is 1, the
`%' expression returns 1:

     (- length (length kill-ring-yank-pointer))
          => 0

therefore,

     (+ arg (- length (length kill-ring-yank-pointer)))
          => 1

and consequently:

     (% (+ arg (- length (length kill-ring-yank-pointer)))
        length)
          => 1

regardless of the value of `length'.

As a result of this, the `setq kill-ring-yank-pointer' expression
simplifies to:

     (setq kill-ring-yank-pointer (nthcdr 1 kill-ring))

What it does is now easy to understand.  Instead of pointing as it did
to the first element of the kill ring, the `kill-ring-yank-pointer' is
set to point to the second element.

   Clearly, if the argument passed to `rotate-yank-pointer' is two, then
the `kill-ring-yank-pointer' is set to `(nthcdr 2 kill-ring)'; and so
on for different values of the argument.

   Similarly, if the `kill-ring-yank-pointer' starts out pointing to
the second element of the kill ring, its length is shorter than the
length of the kill ring by 1, so the computation of the remainder is
based on the expression `(% (+ arg 1) length)'.  This means that the
`kill-ring-yank-pointer' is moved from the second element of the kill
ring to the third element if the argument passed to
`rotate-yank-pointer' is 1.

Pointing to the last element
............................

   The final question is, what happens if the `kill-ring-yank-pointer'
is set to the _last_ element of the kill ring?  Will a call to
`rotate-yank-pointer' mean that nothing more can be taken from the kill
ring?  The answer is no.  What happens is different and useful.  The
`kill-ring-yank-pointer' is set to point to the beginning of the kill
ring instead.

   Let's see how this works by looking at the code, assuming the length
of the kill ring is 5 and the argument passed to `rotate-yank-pointer'
is 1.  When the `kill-ring-yank-pointer' points to the last element of
the kill ring, its length is 1.  The code looks like this:

     (% (+ arg (- length (length kill-ring-yank-pointer))) length)

   When the variables are replaced by their numeric values, the
expression looks like this:

     (% (+ 1 (- 5 1)) 5)

This expression can be evaluated by looking at the most embedded inner
expression first and working outwards:  The value of `(- 5 1)' is 4;
the sum of `(+ 1 4)' is 5; and the remainder of dividing 5 by 5 is
zero.  So what `rotate-yank-pointer' will do is

     (setq kill-ring-yank-pointer (nthcdr 0 kill-ring))

which will set the `kill-ring-yank-pointer' to point to the beginning
of the kill ring.

   So what happens with successive calls to `rotate-yank-pointer' is
that it moves the `kill-ring-yank-pointer' from element to element in
the kill ring until it reaches the end; then it jumps back to the
beginning.  And this is why the kill ring is called a ring, since by
jumping back to the beginning, it is as if the list has no end!  (And
what is a ring, but an entity with no end?)

`yank'
======

   After learning about `rotate-yank-pointer', the code for the `yank'
function is almost easy.  It has only one tricky part, which is the
computation of the argument to be passed to `rotate-yank-pointer'.

   The code looks like this:

     (defun yank (&optional arg)
       "Reinsert the last stretch of killed text.
     More precisely, reinsert the stretch of killed text most
     recently killed OR yanked.
     With just C-U as argument, same but put point in front
     (and mark at end).  With argument n, reinsert the nth
     most recently killed stretch of killed text.
     See also the command \\[yank-pop]."

       (interactive "*P")
       (rotate-yank-pointer (if (listp arg) 0
                              (if (eq arg '-) -1
                                (1- arg))))
       (push-mark (point))
       (insert (car kill-ring-yank-pointer))
       (if (consp arg)
           (exchange-point-and-mark)))

   Glancing over this code, we can understand the last few lines readily
enough.  The mark is pushed, that is, remembered; then the first element
(the CAR) of what the `kill-ring-yank-pointer' points to is inserted;
and then, if the argument passed the function is a `cons', point and
mark are exchanged so the point is put in the front of the inserted
text rather than at the end.  This option is explained in the
documentation.  The function itself is interactive with `"*P"'.  This
means it will not work on a read-only buffer, and that the unprocessed
prefix argument is passed to the function.

Passing the argument
....................

   The hard part of `yank' is understanding the computation that
determines the value of the argument passed to `rotate-yank-pointer'.
Fortunately, it is not so difficult as it looks at first sight.

   What happens is that the result of evaluating one or both of the
`if' expressions will be a number and that number will be the argument
passed to `rotate-yank-pointer'.

   Laid out with comments, the code looks like this:

     (if (listp arg)                         ; if-part
         0                                   ; then-part
       (if (eq arg '-)                       ; else-part, inner if
           -1                                ; inner if's then-part
         (1- arg))))                         ; inner if's else-part

This code consists of two `if' expression, one the else-part of the
other.

   The first or outer `if' expression tests whether the argument passed
to `yank' is a list.  Oddly enough, this will be true if `yank' is
called without an argument--because then it will be passed the value of
`nil' for the optional argument and an evaluation of `(listp nil)'
returns true!  So, if no argument is passed to `yank', the argument
passed to `rotate-yank-pointer' inside of `yank' is zero.  This means
the pointer is not moved and the first element to which
`kill-ring-yank-pointer' points is inserted, as we expect.  Similarly,
if the argument for `yank' is `C-u', this will be read as a list, so
again, a zero will be passed to `rotate-yank-pointer'.  (`C-u' produces
an unprocessed prefix argument of `(4)', which is a list of one
element.)  At the same time, later in the function, this argument will
be read as a `cons' so point will be put in the front and mark at the
end of the insertion.  (The `P' argument to `interactive' is designed
to provide these values for the case when an optional argument is not
provided or when it is `C-u'.)

   The then-part of the outer `if' expression handles the case when
there is no argument or when it is `C-u'.  The else-part handles the
other situations.  The else-part is itself another `if' expression.

   The inner `if' expression tests whether the argument is a minus
sign.  (This is done by pressing the <META> and `-' keys at the same
time, or the <ESC> key and then the `-' key).  In this case, the
`rotate-yank-pointer' function is passed `-1' as an argument.  This
moves the `kill-ring-yank-pointer' backwards, which is what is desired.

   If the true-or-false-test of the inner `if' expression is false
(that is, if the argument is not a minus sign), the else-part of the
expression is evaluated.  This is the expression `(1- arg)'.  Because
of the two `if' expressions, it will only occur when the argument is a
positive number or when it is a negative number (not just a minus sign
on its own).  What `(1- arg)' does is decrement the number and return
it.  (The `1-' function subtracts one from its argument.)  This means
that if the argument to `rotate-yank-pointer' is 1, it is reduced to
zero, which means the first element to which `kill-ring-yank-pointer'
points is yanked back, as you would expect.